Skip to main content

Start Here

Certificate Management​

Use the Certificate Manager API to create and manage SSL certificates for your Media Delivery sites.

You have two options for managing certificates:

  • Upload a certificate: Upload a certificate, chain, and private key directly to the CDN, to make it available for linking to a site.

  • Use a Certificate Template: Use the Certificate Template feature to generate a Certificate Signing Request (CSR) while keeping private keys secure with no need to share them.

    With the Certificate Template feature, you can choose to allow Qwilt to manage the CSR lifecycle using Let's Encrypt, or you can generate and download the CSR to manage the lifecycle yourself using any Certificate Authority (CA).

Note: Your QC User is associated with an organization. When you or any other user within your organization uploads a certificate or creates a template, it is added to a shared pool of certificates and certificate templates available to the users in your organization.


Authentication​

Qwilt APIs support two authentication methods:


Upload a Certificate and Private Key​

Follow these steps to upload an existing certificate, chain, and private key directly to the CDN. Repeat these steps whenever you renew the certificate.


STEP 1: Upload the Certificate and Key​

Use the Upload a Certificate endpoint to upload the certificate, certificate chain, and private key.


Use the Sites API to link the uploaded certificate to a site.

  • Only one certificate can be linked to a site. Ensure that the certificate covers all the site hosts that are configured for secured traffic.
  • If the site is already in production, republish the site to activate the certificate.

Qwilt Managed CSR​

Follow these steps to set up a Qwilt-managed CSR workflow, allowing Qwilt to handle the entire certificate lifecycle, including issuance and renewal, while keeping private keys secure.


STEP 1: Create a Certificate Template​

Use the Create a Certificate Template endpoint to create a Certificate Template.

  • Set autoManagedCertificateTemplate to true to enable Qwilt to manage the certificate lifecycle.

  • Define the certificate details, including the common name, alternative names, and organization details.

  • Ensure the certificate covers all of the site hosts configured for secured traffic.

This API function generates both the CSR and the private key.

The API response includes the csrId. You will need the csrId value for the next step.


STEP 2: Configure a CNAME Record for Domain Verification​

Create a CNAME record to allow Qwilt to verify domain ownership with the CA for certificate issuance and renewal. This step is performed outside of the Qwilt environment, and is your responsibility to manage.

  • Specify the source and destination using the Qwilt provided record name and value (thefromDomain and toDomain values in the Get a signing request endpoint).

    • Retrieve the fromDomain (record name) and toDomain (value) with the Get a signing request endpoint.
    • When sending the request, the csrId from the Certificate Template response is passed as a path parameter.

  • We recommend setting the TTL to a maximum of one day.

Important: The CNAME record is necessary for Qwilt to manage certificate renewals on your behalf, so it must be preserved and not deleted.


Tracking the Status of the CSR​

After the CNAME record is created, Qwilt sends the CSR to the Certificate Authority. It will take approximately 30-60 minutes for the signed certificate to be issued by the CA and become available for use.

You can use the Get a signing request endpoint to check the progress of the request, as indicated by the signingState value in the API response.

These are the possible signingState values:

  • PENDING_CHALLENGE_DELEGATION: Qwilt is waiting for the CNAME record to be created.

  • CHALLENGE_DELEGATION_FAILURE: The CNAME record is invalid. Please check the CNAME record and trigger a new CSR.

  • REQUESTING_CERTIFICATE_FROM_CA: The CSR has been sent to the CA.

  • REQUESTING_CERTIFICATE_FROM_CA_FAILURE: The ACME challenge failed during validation at the CA. Please check the CNAME record and trigger a new CSR.

  • CHALLENGE_PASSED_WAITING_FOR_CA_TO_SIGN: The ACME challenge succeeded.

  • CA_SIGN_FAILURE: The CSR was rejected by the CA. Please contact support.

  • NOTIFY_SITES: The signed certificate was received from the CA and is available for linking. If a site already links to a certificate from the same template, the site is notified to link to and activate the new certificate.

  • NOTIFY_SITES_FAILURE: This status is only possible if a site already links to a certificate from the same template. It means that the new certificate was not successfully activated on the site. Please contact support.

  • NOTIFIED_SITES: The CSR workflow is completed successfully. If a site already links to a certificate from the same template, this status indicates that the new certificate is successfully activated.


Once a signed certificate is available for linking (the signingState described above is either NOTIFY_SITES or NOTIFIED_SITES), you can use the Sites API to link the Certificate to a site.

A linked certificate is activated when you publish the site. If the site is already in production, republish it to activate the new certificate.

From now on, Qwilt manages the entire CSR flow for renewals. A new certificate generated from the template is automatically linked to the same sites as the previous certificate generated from the template, and activated.


Self Managed CSR​

Follow these steps to set up a self-managed CSR workflow, which allows you to work with any CA while keeping private keys secure. With the self-managed workflow, you manage the certificate lifecycle.


STEP 1: Create a Certificate Template​

Use the Create a Certificate Template endpoint to create a Certificate Template.

  • Set autoManagedCertificateTemplate to false.

  • Define the certificate details, including the common name and alternative names.

  • Ensure the certificate covers all of the site hosts configured for secured traffic.

This API function generates both the CSR and the private key. Note the csrId in the API response.


STEP 2: Download the PEM Encoded CSR​

Use the Download a PEM encoded signing request endpoint to download a PEM encoded CSR for submission to the CA.


STEP 3: Submit the CSR to the Certificate Authority​

  • Submit the CSR to the Certificate Authority of your choice.
  • When you get the signed certificate, proceed to step 4.

STEP 4: Upload the Signed Certificate and csrId​

Use the Upload a Certificate endpoint to upload the certificate, certificate chain, and csrId.

The csrId is what links the certificate to the private key.

Optionally, use the expiryNotify attribute to set up automated notifications for when a certificate is approaching its expiration date.


Use the Sites API to link the uploaded certificate to a site.

  • Only one certificate can be linked to a site. Ensure that the certificate covers all the site hosts that are configured for secured traffic.

  • A linked certificate is activated when you publish the site. If the site is already in production, republish it to activate the new certificate.


STEP 6: Renew a Certificate​

To renew a certificate, repeat steps 1-5 above. Note that only one certificate can be linked to a site at a time.

To replace a linked certificate with a new certificate:

  1. Unlink the old certificate. (Do not republish the site. Wait to republish until after you've linked the new certificate.)
  2. Link the new certificate.
  3. Republish the site to deactivate the old certificate and activate the new one.